home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / documents / RFC / rfc1373.txt < prev    next >
Text File  |  1994-08-01  |  20KB  |  676 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                            T. Tignor
  8. Request for Comments: 1373                                             ISI
  9.                                                               October 1992
  10.  
  11.  
  12.                              PORTABLE DUAs
  13.  
  14. Status of this Memo
  15.  
  16.    This memo provides information for the Internet community.  It does
  17.    not specify an Internet standard.  Distribution of this memo is
  18.    unlimited.
  19.  
  20. INTRODUCTION
  21.  
  22.    This document comes in two parts. The first part is for regular
  23.    people who wish to set up their own DUAs (Directory User Interfaces)
  24.    to access the Directory. It includes some brief notes on the
  25.    operation of the DUAs and instructions for their creation and
  26.    installation. The instructions are given in an easy-to-follow, step-
  27.    by-step format. It is fully expected that the user will be able to
  28.    perform the necessary operations as he reads through the instructions
  29.    for the first time and have a working DUA when he finishes. The
  30.    second part is for ISODE-maintainers wishing to provide portable DUAs
  31.    to users. This part gives instructions in a similar but longer,
  32.    step-by-step format. It is fully expected that the maintainer will be
  33.    able to perform the necessary operations as he reads through the
  34.    instructions for the first time and have a working DUA
  35.    package/supporting service when he finishes.
  36.  
  37.    The document currently has four sub-parts for each larger part. The
  38.    sub-parts detail the following DUAs: WHOIS, "de," dixie's "ud" and
  39.    ISODE's "doog." It is intended that additional sub-parts will be
  40.    added to the document as new, portable DUA packages are designed.
  41.  
  42.    Where pertinent, the document assumes ISODE 8.0 is being used.
  43.  
  44.    1.  Instructions for DUA-Users
  45.  
  46.    WHOIS
  47.  
  48.    A WHOIS interface to X.500 may be available on any ISODE-resident
  49.    machine which also runs a DSA (Directory System Agent.) Check with
  50.    your local, ISODE-maintainer. If the service is available, users can
  51.    access the Directory with the following command:
  52.  
  53.         whois -h <hostname> <name in UFN format>
  54.  
  55.  
  56.  
  57.  
  58. Tignor                                                          [Page 1]
  59.  
  60. RFC 1373             DSA Support for Portable DUAs          October 1992
  61.  
  62.  
  63.    <hostname> indicates the name of the host machine offering the WHOIS
  64.    interface, surrounded by quotes. <name in UFN format> refers to a
  65.    special, user-friendly syntax developed by Steve Hardcastle-Kille.
  66.    UFN format is a comma-separated list of DN component values.
  67.    (Attribute types are omitted.) The criteria for identifying DN
  68.    components in UFN is often less stringent than normal.  For example:
  69.  
  70.         @c=US@st=California@o=Information Sciences
  71.         Institute@ou=HPCC@cn=Tom Tignor
  72.  
  73.    could be uniquely specified in UFN syntax as
  74.  
  75.         tignor,isi,ca,us
  76.  
  77.    So to find this entry through WHOIS, one would type:
  78.  
  79.         whois -h "gum.isi.edu" tignor,isi,ca,us
  80.  
  81.    See Steve Hardcastle-Kille's Work in Progress, "User Friendly Naming"
  82.    for details.
  83.  
  84.  
  85.    De
  86.  
  87.    Use of the "de" DUA is fully explained by the program's help section.
  88.    New users should type "?" at the first prompt after installing and
  89.    running the de executable.
  90.  
  91.    The de executable can be created and installed by the following
  92.    simple steps:
  93.  
  94.         If you do not have a file called ".unknown_tailor" in your home
  95.         directory, create it now. This file should contain the following
  96.         single line:
  97.              etcpath:   <fullpathname>/isode/etc/
  98.  
  99.         where <fullpathname> is the full path name of your $HOME
  100.         directory.
  101.  
  102.         If you do not have a directory $HOME/isode/bin, where "$HOME" is
  103.         your home directory, create it now.
  104.  
  105.         ftp the compressed tar file "de-portable.tar.Z" from your local,
  106.         ISODE-resident machine and put it in your isode directory. If
  107.         you cannot find this file locally, it is available by anonymous
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114. Tignor                                                          [Page 2]
  115.  
  116. RFC 1373             DSA Support for Portable DUAs          October 1992
  117.  
  118.  
  119.         ftp from "gum.isi.edu" in the "x500" directory.
  120.  
  121.         cd $HOME/isode
  122.  
  123.         uncompress < de-portable.tar.Z | tar xf -
  124.  
  125.         If your name is listed in the Directory, edit the de/detailor
  126.         file and add a line reading:
  127.              username: <yourDN>
  128.  
  129.         where <yourDN> indicates your Distinguished Name in the
  130.         Directory.
  131.  
  132.         cp de/detailor de/etc/detailor
  133.  
  134.         Edit the CONFIG.make variables BINDIR, ETCDIR and SBINDIR to
  135.         refer to your isode/bin, isode/etc and isode/etc directories,
  136.         respectively.  (The isode/etc directory was created by the
  137.         previous command.)
  138.  
  139.         ranlib libdsap.a
  140.  
  141.         ranlib libisode.a
  142.  
  143.         cd de
  144.  
  145.         ./make all
  146.  
  147.         ./make inst-all
  148.  
  149.    There is one error you may encounter during this procedure, following
  150.    the "./make all" command:
  151.  
  152.         "Redeclaration of sprintf." in general.h
  153.  
  154.    If this error occurs, the following sub-procedure will fix the
  155.    problem:
  156.  
  157.         Invoke your editor for the file ../h/general.h
  158.  
  159.         Search for the string "sprintf".
  160.  
  161.         Cut the line with the "#endif" string which follows the line
  162.         reading:
  163.              char *sprintf ();
  164.  
  165.         Paste the line under the line which reads "#endif". This second
  166.         #endif line is exactly three lines below the current line.
  167.  
  168.  
  169.  
  170. Tignor                                                          [Page 3]
  171.  
  172. RFC 1373             DSA Support for Portable DUAs          October 1992
  173.  
  174.  
  175.         Save the file and quit the editor.
  176.  
  177.    Type "./make all" again. It should now compile smoothly. Finish up by
  178.    typing "./make inst-all".
  179.  
  180.  
  181.    Dixie/Ud
  182.  
  183.    The "ud" DUA is designed for users doing most of their X.500 queries
  184.    in one branch of the DIT (Directory Information Tree.) The DUA
  185.    operates from a predefined "base," a position in the DIT one or more
  186.    branches above the entries to be queried. The base is usually an
  187.    organization name, such as:
  188.  
  189.         @c=US@st=California@o=Information Sciences Institute
  190.  
  191.    Ud starts with a preset base. (See below.) But this base can be
  192.    changed with the "cb" command. "cb" takes the full DN of the new base
  193.    as an argument. For example:
  194.  
  195.         cb @c=GB@o=University College London
  196.  
  197.    With a preset base, searching is easy. The user finds entries below
  198.    the base with the "find" command. "find" takes the last component of
  199.    the DN of the entry as its sole argument. The criteria for the
  200.    argument is very loose. The partial matching performed by ud should
  201.    return the desired data or a clarification request if the name is at
  202.    all close to the real thing.
  203.  
  204.    For example, with a base "@c=US@st=California@o=Information Sciences
  205.    Institute", the RDN
  206.  
  207.         ou=HPCC@cn=Tom Tignor
  208.  
  209.    could be found by entering
  210.  
  211.         find tignor
  212.  
  213.    at the ud prompt.
  214.  
  215.    Other commands in ud are briefly described by the program's help
  216.    section. Interested users should type "?" at the first prompt, after
  217.    installing and running the executable.
  218.  
  219.    "Ud" comes with the "dixie" package, a mini-environment designed
  220.    specifically to support lightweight Directory access. Using ud
  221.    requires that a dixie server is running along with a DSA on your
  222.    local, ISODE-resident machine. Before retrieving the dixie package,
  223.  
  224.  
  225.  
  226. Tignor                                                          [Page 4]
  227.  
  228. RFC 1373             DSA Support for Portable DUAs          October 1992
  229.  
  230.  
  231.    check with your local DSA manager to see that the dixie server is up
  232.    and running.
  233.  
  234.    Once you're sure that everything is set up at the DSA-manager's end,
  235.    the ud executable can be created and installed by the following
  236.    simple steps:
  237.  
  238.         If you do not have a directory $HOME/isode/bin, where "$HOME" is
  239.         your home directory, create it now.
  240.  
  241.         ftp (anonymously) the compressed tar file "dixie-<version
  242.         #>.tar.Z", where <version #> is the number of the latest
  243.         release, from "terminator.cc.umich.edu" and put it in your isode
  244.         directory. The file is available in the "x500" directory on
  245.         terminator.
  246.  
  247.         cd $HOME/isode
  248.  
  249.         uncompress < dixie-<version #>.tar.Z | tar xf -
  250.  
  251.    This creates the dixie environment. As a user interested in ud only,
  252.    there are a number of things in the package that will be taking up
  253.    space to no purpose. The following sequence of commands will get rid
  254.    of them.
  255.  
  256.         cd dixie-<version #>
  257.  
  258.         rm -r dos
  259.  
  260.         rm -r macintosh
  261.  
  262.         rm -r server
  263.  
  264.         rm -r vms
  265.  
  266.         cd ..
  267.  
  268.    That done, we continue to bring ud to life.
  269.  
  270.         cd dixie-<version #>
  271.  
  272.         Edit the file "ud/ud.h". There are two constants for which you
  273.         will need to supply new values: DEFAULT_BASE and DEFAULT_SERVER.
  274.         DEFAULT_BASE identifies ud's "base" upon startup, as described
  275.         above.  It takes a quoted DN as a value, e.g.,
  276.         "@c=US@st=California@o=Information Sciences Institute".
  277.         DEFAULT_SERVER identifies the machine which hosts the dixie
  278.         server, i.e. your local, ISODE-resident machine. This constant
  279.  
  280.  
  281.  
  282. Tignor                                                          [Page 5]
  283.  
  284. RFC 1373             DSA Support for Portable DUAs          October 1992
  285.  
  286.  
  287.         takes a quoted string as a value, e.g., "gum.isi.edu".
  288.  
  289.         Edit the file "Makefile". Set the value of the BINDIR variable
  290.         to "<mypath>/isode/bin", where <mypath> is the full pathname of
  291.         the user's home directory.
  292.  
  293.         make depend-ud
  294.  
  295.         make ud-only
  296.  
  297.         make inst-ud
  298.  
  299.  
  300.    Doog
  301.  
  302.    The "doog" DUA retrieves information on entries supplied by the user
  303.    in UFN format. UFN format refers to a special, user-friendly syntax
  304.    developed by Steve Hardcastle-Kille. UFN format is a comma-separated
  305.    list of DN component values. (Attribute types are omitted.) The
  306.    criteria for identifying DN components in UFN is often less stringent
  307.    than normal.  For example:
  308.  
  309.         @c=US@st=California@o=Information Sciences
  310.         Institute@ou=HPCC@cn=Tom Tignor
  311.  
  312.    could be specified in UFN syntax (and doog) as
  313.  
  314.         tignor,isi,ca,us
  315.  
  316.    See Steve Hardcastle-Kille's Work in Progress, "User Friendly Naming"
  317.    for details.
  318.  
  319.    Other commands in doog are briefly described by the program's help
  320.    section. Interested users should type "?" at the first prompt, after
  321.    installing and running the executable.
  322.  
  323.    The doog executable can be created and installed by the following
  324.    simple steps:
  325.  
  326.         If you do not have a file called ".unknown_tailor" in your home
  327.         directory, create it now. This file should contain the following
  328.         single line:
  329.              etcpath:   <fullpathname>/isode/etc/
  330.  
  331.         where <fullpathname> is the full path name of your $HOME
  332.         directory.
  333.  
  334.         If you do not have a directory $HOME/isode/bin, where "$HOME" is
  335.  
  336.  
  337.  
  338. Tignor                                                          [Page 6]
  339.  
  340. RFC 1373             DSA Support for Portable DUAs          October 1992
  341.  
  342.  
  343.         your home directory, create it now.
  344.  
  345.         ftp the compressed tar file "doog-portable.tar.Z" from your
  346.         local, ISODE-resident machine and put it in your isode
  347.         directory. If you cannot find this file locally, it is available
  348.         by anonymous ftp from "gum.isi.edu" in the "x500" directory.
  349.  
  350.         cd $HOME/isode
  351.  
  352.         uncompress < doog-isode-8.0.tar.Z | tar xf -
  353.  
  354.         Edit the CONFIG.make variables BINDIR, ETCDIR and SBINDIR to
  355.         refer to your isode/bin, isode/etc and isode/etc directories,
  356.         respectively.  (The isode/etc directory was created by the
  357.         previous command.)
  358.  
  359.         ranlib libdsap.a
  360.  
  361.         ranlib libisode.a
  362.  
  363.         cd doog
  364.  
  365.         ./make all
  366.  
  367.         ./make inst-all
  368.  
  369.    2.  Instructions for ISODE-Maintainers
  370.  
  371.    WHOIS
  372.  
  373.    "WHOIS" is a simple program already available at most UNIX
  374.    workstations and hosts. It is normally used to access the database of
  375.    users at NIC.DDN.MIL. The instructions below explain how to use WHOIS
  376.    to access data in the White Pages Pilot X.500 database. These
  377.    instructions are taken nearly word for word from the "PSI White Pages
  378.    Pilot Project Administrator's Guide," section 2.8.3.
  379.  
  380.    Choose a machine in your local environment which is running the pilot
  381.    project software. This machine will offer the white pages service via
  382.    a network port offering an emulation of the WHOIS service.
  383.  
  384.    On this machine, modify the /etc/services file so that it contains an
  385.    entry like this:
  386.  
  387.         whitepages 17005/tcp
  388.  
  389.    Next, edit the file /etc/servers so that it has an entry like this:
  390.  
  391.  
  392.  
  393.  
  394. Tignor                                                          [Page 7]
  395.  
  396. RFC 1373             DSA Support for Portable DUAs          October 1992
  397.  
  398.  
  399.         whitepages tcp  $(SBINDIR)in.whitepages
  400.  
  401.    Because most user interfaces to WHOIS, e.g., whois(1c), do not allow
  402.    the user to specify a special port, you should probably also add this
  403.    line as well:
  404.  
  405.         whois tcp$(SBINDIR)in.whitepages
  406.  
  407.    If you already have a line for whois in the servers file, then you
  408.    are already running a WHOIS service, and you should NOT add a second
  409.    whois line. This machine is not a good choice for running the white
  410.    pages via WHOIS emulation.
  411.  
  412.    Note that on newer systems derived from Berkeley UNIX, /etc/servers
  413.    is called /etc/inetd.conf.
  414.  
  415.         The whitepages Command
  416.  
  417.    On those systems which are to access the white pages via the network
  418.    and not locally (i.e., those systems which are not running the pilot
  419.    project software), you should determine how the user invokes the
  420.    WHOIS service via the network. For UNIX systems, you should provide a
  421.    shell script like this:
  422.  
  423.         : run this script through /bin/sh
  424.  
  425.         exec /usr/ucb/whois -h wp.psi.net "$*"
  426.  
  427.    where the name of a host running the pilot project software is
  428.    substituted for whitepages, e.g., wp.psi.net. This host must have the
  429.    files /etc/services and /etc/servers edited as described above.
  430.  
  431.  
  432.    De
  433.  
  434.    The compressed tar file for "de" can be created by the following
  435.    sequence of commands. (Note: In the instructions which follow,
  436.    <toplevel> indicates the top level of the ISODE distribution.)
  437.  
  438.         cd <toplevel>/others/quipu/uips
  439.  
  440.         Edit the de/detailor file to set the following options:
  441.  
  442.              dsa_address:            (the address of your DSA)
  443.              default_country:        (your country)
  444.              default_org:            (your organization)
  445.  
  446.         cp de/make temp1
  447.  
  448.  
  449.  
  450. Tignor                                                          [Page 8]
  451.  
  452. RFC 1373             DSA Support for Portable DUAs          October 1992
  453.  
  454.  
  455.         Edit the de/make file so that the last line reads as follows:
  456.  
  457.              exec $M TOPDIR=../ -f ../CONFIG.make -f Makefile ${1+"$@"}
  458.  
  459.         tar -cf de-portable.tar de/*
  460.  
  461.         mv temp1 de/make
  462.  
  463.         mv de-portable.tar <aboveETCDIR>
  464.              (Here, <aboveETCDIR> is the directory immediately above
  465.              ETCDIR.)
  466.  
  467.         cd <aboveETCDIR>
  468.  
  469.         tar -rf de-portable.tar etc/dsaptailor etc/isomacros
  470.         etc/oidtable.at etc/oidtable.oc etc/oidtable.gen
  471.  
  472.         mv de-portable.tar <toplevel>
  473.  
  474.         cd <toplevel>
  475.  
  476.         cp config/CONFIG.make .
  477.  
  478.         tar -rf de-portable.tar h/* h/quipu/* util/* CONFIG.make
  479.         libdsap.a libisode.a
  480.  
  481.         rm CONFIG.make
  482.  
  483.         compress de-portable.tar
  484.  
  485.    The compressed tar file for de will appear in the top level directory
  486.    of the ISODE distribution as "de-portable.tar.Z".
  487.  
  488.  
  489.    Dixie/Ud
  490.  
  491.    The latest version of the dixie distribution is available by
  492.    anonymous ftp at "terminator.cc.umich.edu" in the "x500" directory.
  493.    The file is named "dixie-<version #>.tar.Z", where <version #> is the
  494.    number of the latest release.
  495.  
  496.    In order for anyone to use dixie clients, there must be a running
  497.    dixie server which they can connect to. To set up the dixie server,
  498.    the DSA manager should take the dixie package and explode/uncompress
  499.    it in the top level directory of the ISODE distribution. This is done
  500.    with the following command:
  501.  
  502.         uncompress < dixie-<version #>.tar.Z | tar xf -
  503.  
  504.  
  505.  
  506. Tignor                                                          [Page 9]
  507.  
  508. RFC 1373             DSA Support for Portable DUAs          October 1992
  509.  
  510.  
  511.    where <version #> is the version number of your dixie package.  This
  512.    will create a "dixie-<version #>" directory. The dixie server, dixie
  513.    library and any DUAs included with the package will be in this
  514.    directory branch. Software to support dixie on machines other than
  515.    UNIX is included as well. This software is stored in the directories
  516.    "dos", "macintosh" and "vms". UNIX users should feel free to delete
  517.    these directories and all their contents. Commands of the form:
  518.  
  519.         rm -r <dirname>
  520.  
  521.    where <dirname> is the directory name, should accomplish this task.
  522.  
  523.    In the top level of the dixie distribution is a file called
  524.    "Makefile". The file holds several variables which should be
  525.    configured to match those of your ISODE environment.
  526.  
  527.  
  528.            BINDIR                  ISODEINCLUDEDIR
  529.            ETCDIR                  LIBDIR
  530.            INCLUDEDIR              ISODELIBS
  531.            INSTLIBDIR
  532.  
  533.  
  534.    In the "server" directory below the top level of the dixie
  535.    distribution is another "Makefile" file. Configure the ISODELIBS
  536.    variable in this file, as well.
  537.  
  538.    After setting these variables, cd to the top level of the dixie
  539.    distribution and type the following commands:
  540.  
  541.            make depend-server
  542.            make server-only
  543.            make inst-server
  544.  
  545.  
  546.    This will create and install the dixie server in your ETCDIR.  cd to
  547.    the ETCDIR and type "dixie" to start the server.
  548.  
  549.  
  550.    Doog
  551.  
  552.    The compressed tar file for "doog" can be created by the following
  553.    sequence of commands. (Note: In the instructions which follow,
  554.    <toplevel> indicates the top level of the ISODE distribution.)
  555.  
  556.         cd <toplevel>/others/quipu/uips
  557.  
  558.         cp doog/make temp1
  559.  
  560.  
  561.  
  562. Tignor                                                         [Page 10]
  563.  
  564. RFC 1373             DSA Support for Portable DUAs          October 1992
  565.  
  566.  
  567.         Edit the doog/make file so that the last line reads as follows:
  568.  
  569.              exec $M TOPDIR=../ -f ../CONFIG.make -f Makefile ${1+"$@"}
  570.  
  571.         cp doog/query/make temp2
  572.  
  573.         Edit the doog/query/make file so that the last line reads as
  574.         follows:
  575.  
  576.              exec $M TOPDIR=../../ -f ../../CONFIG.make -f Makefile
  577.              ${1+"$@"}
  578.  
  579.         tar -cf doog-portable.tar doog/*
  580.  
  581.         mv temp1 doog/make
  582.  
  583.         mv temp2 doog/query/make
  584.  
  585.         mv doog-portable.tar ../../..
  586.  
  587.         cd ../../..
  588.  
  589.         cp config/CONFIG.make .
  590.  
  591.         tar -rf doog-portable.tar h/* h/quipu/* util/* CONFIG.make
  592.         libdsap.a libisode.a
  593.  
  594.         rm CONFIG.make
  595.  
  596.         mv doog-portable.tar <aboveETCDIR>
  597.              (Here, <aboveETCDIR> is the directory immediately above
  598.              ETCDIR.)
  599.  
  600.         cd <aboveETCDIR>
  601.  
  602.         tar -rf doog-portable.tar etc/dsaptailor etc/isomacros
  603.         etc/oidtable.at etc/oidtable.gen etc/oidtable.oc
  604.  
  605.         compress doog-portable.tar
  606.  
  607.    The compressed tar file for doog will appear in the directory
  608.    immediately above ETCDIR as "doog-portable.tar.Z".
  609.  
  610. Security Considerations
  611.  
  612.    Security issues are not discussed in this memo.
  613.  
  614.  
  615.  
  616.  
  617.  
  618. Tignor                                                         [Page 11]
  619.  
  620. RFC 1373             DSA Support for Portable DUAs          October 1992
  621.  
  622.  
  623. Author's Address
  624.  
  625.    Tom Tignor
  626.    University of Southern California
  627.    Information Sciences Institute
  628.    4676 Admiralty Way
  629.    Marina del Rey, CA 90292
  630.  
  631.    Phone: (310) 822-1511
  632.    EMail: tpt2@isi.edu
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.  
  672.  
  673.  
  674. Tignor                                                         [Page 12]
  675.  
  676.